home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Extra 1996 #5 / Amiga Plus Extra 1996 May.iso / editoren / gmplay_v0.9b / gmplay.doc < prev    next >
Text File  |  1996-08-01  |  11KB  |  326 lines
  1.  
  2.  
  3.  
  4.  
  5.                             GMPlay v0.9 beta
  6.                             ----------------
  7.         MIDI file player and General MIDI tone generator emulation
  8.                    (c) 1995,1996 Sonic Dreams Software
  9.  
  10.  
  11.  
  12.     
  13. INTRODUCTION
  14. ------------
  15. I often heard from PeeCee users:
  16. "You can't play MIDI files on your Amiga without external MIDI hardware,
  17. and my SoundFucker card is cheaper! Ha ha ha".
  18. But since a Turing machine could easily emulate a Cray supercomputer,
  19. here it comes this buggy program called GMPlay.
  20.  
  21. I got it working over a year ago, but only now I decided to release it,
  22. because the new improved version is working but not completely clean
  23. and ready.
  24.  
  25. All you need is a FAST Amiga, and MIDI files will come straight from the
  26. old good Paula to your ears.
  27.  
  28.  
  29. FEATURES
  30. --------
  31.     - Full emulation of a General MIDI tone generator
  32.     - Up to 32 voices polyphony with dynamic allocation
  33.     - Selectable playback sample rate
  34.     - Volume/PanPot/Expression/Sustain controls emulation
  35.     - Pitch Bender/Bend Range emulation
  36.     - Up to 64 drum samples
  37.     - Up to 128 instrument samples
  38.     - Use standard 8SVX samples (one octave only)
  39.     - Fibonacci Delta packed samples support
  40.     - MIDI file formats 0 and 1 compatible
  41.     - Up to 32 tracks
  42.  
  43.  
  44. REQUIREMENTS
  45. ------------
  46.     - OS2.0 or higher
  47.     - 68020 processor or higher
  48.     - 1MB or more CHIP memory
  49.     - FAST memory highly recomended
  50.     - A 50MHz 68060 CPU is required if you wanna take full advantage
  51.       of using highest audio sampling rate...
  52.  
  53.  
  54. DISCLAIMER
  55. ----------
  56. WARNING: I'm not responsible for any loss or damage caused by this program
  57. to your software, your hardware, your house, or your life, even if you use
  58. it in perfect respect of my directions.
  59.  
  60. YOU CAN USE THE PROGRAM AS IS, AT YOUR OWN RISK.
  61.  
  62. You can freely distribute this program for non-commercial purposes only,
  63. but you must not modify the archive contents.
  64. However you can replace instrument samples in your installation to fit
  65. your own taste.
  66.  
  67. COMMERCIAL DISTRIBUTION OR INCLUDING IN MAGAZINES OR COVER DISKS
  68. IS FORBIDDEN WITHOUT MY WRITTEN PERMISSION.
  69.  
  70. Explicit permission to Fred Fish and Urban Dominik Müller to include
  71. this software on Fish disks, Aminet and Aminet CDs.
  72. Thanks for keeping Amiga alive, guys.
  73.  
  74.  
  75. INSTALLATON
  76. -----------
  77. Extract the files in the archive in a directory of your choice, then
  78. assign GM: to point to that dir. For example: 
  79.  
  80.     Assign GM: Work:GMPlayer
  81.  
  82. You may want to make this assignment at boot time by inserting it in your
  83. S:user-startup.
  84.  
  85.  
  86. USING GM PLAYER
  87. ---------------
  88. Using GMPlay is pretty simple, just type:
  89.  
  90.     GM:GMPlay <filename> [options]
  91.  
  92. where <filename> is the name of a standard MIDI file (try GM:Songs/Test),
  93. and .MID extension is not necessary.
  94.  
  95. You can use the following options:
  96.  
  97. -v<volume>  Change master volume (range 0..64 - default 64)
  98.  
  99. Lets you adjust output level not to hurt somebody if you connect your
  100. Amiga to a volume-less 100.000 watts amplifier. 
  101.  
  102. -r<rate>    Change playback rate (range 3608..57734 - default 16726 Hz)
  103.  
  104. A higher rate requires a faster machine.
  105. Also remember that you MUST use a 31 KHz video mode to break the limit
  106. of the audio DMA bandwidth (28867 Hz).
  107.  
  108. -b<buffer>  Change the output buffer size (range 32..128 - default 64 KB)
  109.  
  110. The value you supply stand for ONE buffer, but remember that the
  111. program use FOUR times this value to do stereo double buffering.
  112. Giving a value of 128 will eat 512 KB of your CHIP mem.
  113. Larger buffers may improve playing on complex songs, but also cause
  114. you to wait longer if you want to stop playing (see LIMITATIONS).
  115.  
  116. -g<gain>    Change the output gain (range -3..+3 - default 0 = 0 dB)
  117.  
  118. This let you change digital mix gain from -18 dB to +18 dB to prevent
  119. very loud songs from clipping when forced to 8-bit output. Lower gain
  120. if you hear distortion, or raise it if the song sounds too soft.
  121.              
  122. -p<poly>    Change emulation polyphony (range 8..32 - default 24 = GM std)
  123.  
  124. This option was included to speed up emulation on playing very simple
  125. songs. Since oscillators are now managed by a linked list, the effect
  126. on program performance is almost null. You can still use this option
  127. to limit the maximum number of voices, or if you need more than 24.
  128.  
  129. -f          Turn FAST mode on (default normal mode)
  130.  
  131. FAST mode disables stereo mix and audio data bounds check to increase
  132. efficiency. If the voice mix lead to an overflow, you'll probably get
  133. noise since audio data is no longer clipped to maximum or minimum value.
  134. If this happens, try lowering gain with the -g option.
  135.  
  136. -m          Leave multi-tasking enabled (default disabled)
  137.  
  138. The program use Forbid() and Permit() calls to tell the other tasks to
  139. leave him alone during calculations. If you own a fast machine and you're
  140. bored by the jumpy mouse pointer, use this option.
  141.  
  142. -i          Prints out some info about song (default OFF)
  143.  
  144. This option show you parameters and other song information before song
  145. starts playing. In this pre-release you will see also debug printf() calls
  146. during play, so it's not recomended for speed. If you don't want any
  147. output you can redirect the command to NIL: as follows:
  148.  
  149. GMPlay >NIL: <filename> [options]
  150.  
  151.  
  152. HINTS AND TIPS
  153. --------------
  154. - If the song comes out "not what you call smooth" try one (or two)
  155.   of the following things:
  156.   
  157.     - Turn on fast mode
  158.     - Lower playback rate
  159.     - Increase buffer size
  160.     - Buy a faster machine :-(
  161.     - Buy a GM tone generator 8-((
  162.     - Eat your MIDI disks and sing it out loud... :-o<((
  163.  
  164. - To stop playing, press CTRL-C inside the output window (then wait...)
  165.   or issue a break command to GMPlay process.
  166.  
  167. - When a sample is not located GMPlay tries to load the default sample,
  168.   that is GM:Tones/Piano for instruments and GM:Drums/RimShot for drums.
  169.   Those samples MUST exist or the program will abort.
  170.  
  171. - You may want to use GMPlay from your favourite disk utility program.
  172.   This example shows how to call GMPlay from DiskMaster II.
  173.   First add this line to DiskMaster's configuration script:
  174.  
  175.     AddAutoCmd MThd,Extern GM:GMPlay %s
  176.  
  177. ...then run DiskMaster II and just double-click a MIDI file to hear it!
  178.  
  179.  
  180. ABOUT MAPS:
  181. -----------
  182. The files named ToneMap.dat and DrumMap.dat contain the drum kit and
  183. instrument set definition.
  184. You can edit the maps with a binary disk editor, or try to match them
  185. with your own samples.
  186.  
  187. Here's a brief description of map structure:
  188.  
  189. Each entry of the map is 16 bytes long.
  190. Starting from byte 0 of each 16-byte group, you find the name of the
  191. sample. You should not exceed the first 12 bytes including a zero to
  192. terminate string. If you put a 0 in the first byte any program change
  193. to that entry will be ignored.
  194.  
  195. - Tone map:
  196.  
  197. Contain 128 entries. Each row have the following format:
  198.  
  199.     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  200.     |0|1|2|3|4|5|6|7|8|9|A|B|C|D|E|F|
  201.     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  202.      \_____________________/ \___/ |
  203.                 |              |   | 
  204.                NAME           RSV FLAG
  205.                                    
  206. NAME: Sample name (path is GM:Tones/).
  207.  
  208. RSV : Reserved field.
  209.  
  210. FLAG: A flag indicating decay length varying with the pitch (like piano
  211.       and other percussive instruments). This is not yet implemented.
  212.  
  213. - DrumMap:
  214.  
  215. Contain 64 entries. Each row have the following format:
  216.  
  217.     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  218.     |0|1|2|3|4|5|6|7|8|9|A|B|C|D|E|F|
  219.     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  220.      \_____________________/ \_/ | |
  221.                 |             |  | | 
  222.                NAME           | RSV|
  223.                             LINK  POS
  224.                                         
  225. NAME: Sample name (path is GM:Drums/).
  226.  
  227. LINK: Two exclusive links with other drums. In other words when that
  228.       sample is played, any other occurrence of the same sample, or any
  229.       occurrence of a linked sample is muted. For example, a closed or
  230.       pedal high hat should mute a open one to get a realistic result.
  231.       Zero means no link.
  232.       
  233. RSV : Reserved field.
  234.  
  235. POS : Stereo position for that drum (Note that drum samples stereo
  236.       position is not affected by pan-pot control on channel #10, but
  237.       only by this setting).
  238.  
  239. WARNING: All this stuff is subject to changes prior to final release!!!
  240.  
  241.  
  242. KNOWN BUGS
  243. ----------
  244. (Before you start sending me mail-packed nuclear weapons...
  245. ...have you read the DISCLAIMER???)
  246.  
  247.     - The program will allocate all audio channels even if two are used.
  248.  
  249. This will come useful when I'll do 14-bit output on my PowerPC equipped
  250. Amiga 6000.
  251.  
  252.     - The program will crash your machine with some complex song files.
  253.  
  254. This happens since I modified most of the code and then totally crashed
  255. my old 40MB haed-drive, according strictly with the Murphy's law!
  256. Now I'm trying to get the new sources working before my 70th birthday.
  257.  
  258.  
  259. LIMITATIONS
  260. -----------
  261.     - No multiple drum kits.
  262.     - Modulation control change not supported.
  263.     - Envelopes added on v0.7 and later removed.
  264.  
  265. This mean no release stage after a note off command, and also unwanted
  266. sustain on piano-like instruments.
  267. I'm working to add all three features to the final release.
  268.  
  269.     - No graphical interface
  270.     - The program doesn't stop immediately
  271.     
  272. I've tried to do everything system friendly, but I'm not so deep in system
  273. programming and my documentation is poor and obsolete.
  274. If you have suggestions or you want to build a graphical interface, please
  275. contact me.
  276.  
  277.     - Supplied samples are noisy
  278.  
  279. All supplied samples were taken with a cheap 8-bit sampler.
  280. Anyone who own a 16-bit sampler can grab 16-bit samples and then convert
  281. them to 8-bit, eliminating noise completely.
  282.  
  283.     - Slow on basic machines (A1200 or even A3000).
  284.     
  285. The output calculation is already hand optimized 020+ assembly.
  286. If you need to play just classical piano songs (with one or two tracks)
  287. it should work fine. Using GMPlay on my 50 Mhz 68030 I'm able to play most
  288. but not all multi-tracked tunes.
  289. A new version of the program, using FAST mem buffers and other brand new
  290. tricks (OS legal, I hope!) is under development.
  291. It will bring to FAST mem owners more than twice the current calc speed.
  292. For systems with CHIP mem only, there's just a triple-buffers scheme that
  293. I left off that could help.
  294.  
  295.     - No DSP effects emulation
  296.     
  297. Wadda ya want from me, man???
  298. Maybe available in release 999.9, before late spring 2013!!!
  299.  
  300.  
  301. HISTORY
  302. -------
  303.  
  304.     0.9 beta - Finished May 7,1995 - Released February 7,1996 :-(((
  305.     
  306.  
  307. ABOUT SONIC DREAMS SOFTWARE
  308. ---------------------------
  309. Code and "Crazy" song written by Alessandro De Luca.
  310. Fibonacci unpack routine based on Emanuele Viola's work published
  311. on Amiga Magazine #60.
  312.  
  313. This program is FREEWARE (NOT PUBLIC DOMAIN!!!).
  314. If you find it useful, send me a money donation to encourage further
  315. development of this and other projects.
  316.     
  317. Snail:
  318.  
  319.     Alessandro De Luca
  320.     Via degli Oleandri s/n
  321.     98035 Giardini Naxos (ME)
  322.     ITALY
  323.  
  324. E-Mail:
  325.  
  326.     hairy@asterix.unime.it